import { Quat, Vec3 } from "cc";
import { GridSensorBase } from "./GridSensorBase";

/**
 * @en
 * An interface for GridSensor perception that defines the grid cells and collider detecting strategies.
 * 
 * @zh
 * 用于定义网格单元格和碰撞器检测策略的 GridSensor 感知的接口。
 * 
 */
export interface IGridPerception {
    rotateWithAgent: boolean;
    colliderMask: number;

    /**
     * @en
     * Converts the index of the cell to the 3D point (y is zero) relative to grid center
     * @zh
     * 将单元格的索引转换为相对于网格中心的 3D 点（y 为零）
     * 
     * @param cellIndex 
     */
    getCellLocalPosition(cellIndex: number): Vec3;


    /**
     * @en
     *  Converts the index of the cell to the 3D point (y is zero) in world space
     * based on the result from GetCellLocalPosition()
     * 
     * @zh
     * 根据 GetCellLocalPosition() 的结果，将单元格的索引转换为世界空间中的 3D 点（y 为零）
     * 
     * @param cellIndex 
     */
    getCellGlobalPosition(cellIndex: number): Vec3;


    getGridRotation(): Quat;

    /**
      * @en
      * Perceive the latest grid status. Detect colliders for each cell, parse the collider arrays,
      * then trigger registered sensors to encode and update with the new grid status.
      * @zh
      *  感知最新的网格状态。检测每个单元格的碰撞器，解析碰撞器数组，然后触发已注册的传感器以使用新的网格状态进行编码和更新。
      *  
      */
    perceive(): void;

    /**
     * @en
     * Same as Perceive(), but only load data for debug gizmo.
     * @zh
     * 与 Perceive() 相同，但仅为调试图形加载数据。
     */
    updateGizmo(): void;

    /**
     * @en
     * Register a sensor to this GridPerception to receive the grid perception results.
     * When the GridPerception perceive a new observation, registered sensors will be triggered
     * to encode the new observation and update its data.
     * 
     * @zh
     * 将传感器注册到此 GridPerception 以接收网格感知结果。
     * 当 GridPerception 感知到新的观察时，将触发已注册的传感器以对新观察进行编码并更新其数据。
     * 
     * 
     * @param sensor 
     */
    registerSensor(sensor: GridSensorBase): void;

    /**
     * 
     * @en
     * Register an internal debug sensor.
     * Debug sensors will only be triggered when drawing debug gizmos.
     * 
     * @zh
     *  注册内部调试传感器。
     * 仅在绘制调试图形时才会触发调试传感器。
     * 
     * @param debugSensor 
     */
    registerDebugSensor(debugSensor: GridSensorBase): void;
}